# mergeStateControlVars.R

mergeStateControlVars <- function(stateYoung, yearYoung, colElim = TRUE) {
  # This function takes a factor specifying the state in which each subject
  # in a dataset lived when young, and a numeric or integer variable 
  # indicating the year in which each subject was young.  It returns a set of 
  # control variables that vary according to the state and year in which the 
  # subject was young, e.g., doctors per capita, % black.  
  if (! class(stateYoung) %in% 'factor') {
    stop("stateYoung must be a factor.")
  }
  if (! class(yearYoung) %in% c('numeric', 'integer')) {
    stop("yearYoung must be of class 'numeric' or 'integer")
  }
  
  
  # SOURCE FILES THAT LOAD AND IMPUTE DATA
  # The files sourced below actually load the data on state-year control 
  # variables.  They also impute missing values.  
  stateControlsEnv <- new.env()
  sys.source(
    file  = 'twoPartyVote.R', 
    envir = stateControlsEnv)  
  sys.source(
    file  = 'stateYearControls.R',       
    envir = stateControlsEnv)  

  
  # MERGE VARIABLES [2011 07 03]
  stateControlsEnv$varNamesToImport <- c(
    'VAP.turnout', 
    'pop', 
    'percentBlack', 
    'percentForeignBorn', 
    'percentUrban', 
    'percentWorkInManufacturing', 
    'doctorsPerCapita', 
    'higherEdEnrollmentPerCapImputed', 
    'blendedTeacherSalaries',
    'teacherStudentRatio',
    'RepublicanPresident', 
    'USHouseMedian')
  stateYearVars <- merge(
    x     = data.frame(rownum=1:length(stateYoung), stateYoung, yearYoung), 
    y     = stateControlsEnv$stateYearVars[, c('state', 'year', stateControlsEnv$varNamesToImport)], 
    by.x  = c('stateYoung', 'yearYoung'), 
    by.y  = c('state',   'year'), 
    all.x = TRUE, 
    all.y = FALSE, 
    sort  = FALSE)
  stateYearVars <- merge(
    x     = stateYearVars, 
    y     = na.omit(stateControlsEnv$twoPartyVote[, c('state.2L', 'YEAR', 'Dem.2p')]), 
    by.x  = c('stateYoung', 'yearYoung'), 
    by.y  = c('state.2L',   'YEAR'), 
    all.x = TRUE, 
    all.y = FALSE, 
    sort  = FALSE)
  
  # merge() returns the data in an arbitrary order.  Here, we use order() to 
  # make the order of the merged dataset correspond to the order of the other
  # data (e.g., stateYoung, yearYoung, eqwlth, goveqinc, and so on).  [2012 07 11]
  stateYearVars <- stateYearVars[order(stateYearVars$rownum), ]  
  
  
  # Eliminate columns that aren't state-year covariates.
  if (colElim) {
    colsToEliminate <- colnames(stateYearVars) %in% c('stateYoung', 'yearYoung', 'rownum')
    stateYearVars <- stateYearVars[, !colsToEliminate]
  }
  stateYearVars
}

